10.1 List Functions

This section describes a number of simple operations on lists, i.e., chains of cons cells.

Function: cl-caddr x

This function is equivalent to (car (cdr (cdr x))). Likewise, this package defines all 24 cxxxr functions where xxx is up to four ‘a’s and/or ‘d’s. All of these functions are setf-able, and calls to them are expanded inline by the byte-compiler for maximum efficiency.

Function: cl-first x

This function is a synonym for (car x). Likewise, the functions cl-second, cl-third, …, through cl-tenth return the given element of the list x.

Function: cl-rest x

This function is a synonym for (cdr x).

Function: cl-endp x

This function acts like null, but signals an error if x is neither a nil nor a cons cell.

Function: cl-list-length x

This function returns the length of list x, exactly like (length x), except that if x is a circular list (where the CDR-chain forms a loop rather than terminating with nil), this function returns nil. (The regular length function would get stuck if given a circular list. See also the safe-length function.)

Function: cl-list* arg &rest others

This function constructs a list of its arguments. The final argument becomes the CDR of the last cell constructed. Thus, (cl-list* a b c) is equivalent to (cons a (cons b c)), and (cl-list* a b nil) is equivalent to (list a b).

Function: cl-ldiff list sublist

If sublist is a sublist of list, i.e., is eq to one of the cons cells of list, then this function returns a copy of the part of list up to but not including sublist. For example, (cl-ldiff x (cddr x)) returns the first two elements of the list x. The result is a copy; the original list is not modified. If sublist is not a sublist of list, a copy of the entire list is returned.

Function: cl-copy-list list

This function returns a copy of the list list. It copies dotted lists like (1 2 . 3) correctly.

Function: cl-tree-equal x y &key :test :test-not :key

This function compares two trees of cons cells. If x and y are both cons cells, their CARs and CDRs are compared recursively. If neither x nor y is a cons cell, they are compared by eql, or according to the specified test. The :key function, if specified, is applied to the elements of both trees. See Sequences.